Add TouchRotate3/4/5 Cw/Ccw triggers alongside the existing swipe and
pinch families (same hardcoded-per-finger-count shape — true arbitrary
N-finger parameterization is still open in TODO §6). Rotation is
detected from the averaged per-finger angle change around the cluster
centroid; cross-finger averaging gives a √N noise-floor improvement
over single-finger angular drift. Rotation classification runs before
pinch and swipe so a clearly twisting cluster wins over incidental
spread or translation.

Tuning lives under input { touchscreen { gestures { } } }:
rotation-threshold (min radians to latch), rotation-ratio (how much
rotation arc length must dominate swipe/spread by), and
rotation-progress-distance (radians that map to IPC progress ±1.0).

While here, refactor GestureProgress's overloaded delta_x / delta_y
fields into a typed GestureDelta enum (Swipe { dx, dy } / Pinch
{ d_spread } / Rotate { d_radians }) so each gesture family can carry
its own natural shape instead of stuffing rotation radians into an
empty y slot.

NOTE: rotation detection is an early PoC and is currently buggy and
intermittent on real hardware — recognition can misfire, lock at the
wrong finger count, or fail to latch. The math, IPC, unit tests, and
bind plumbing are all in place, but real-world tuning and edge cases
(lock grace period, finger-lift rebasing under rotation, noise
thresholds) still need debugging. Parking it here so the rest of the
work lands and the rotation pass can resume later.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Collapse the 40 hardcoded Touch*/Touchpad* enum variants into 5
parameterized struct variants driven by KDL properties, so the
compositor no longer hardcodes the legal finger counts into the trigger
name. User configs go from:

    TouchSwipe3Up        { focus-workspace-up; }
    TouchEdgeTop:Left    { spawn "..."; }
    TouchpadSwipe4Left   { ... }

to the property form:

    TouchSwipe    fingers=3 direction="up"            { focus-workspace-up; }
    TouchEdge     edge="top" zone="left"              { spawn "..."; }
    TouchpadSwipe fingers=4 direction="left"          { ... }

Each family keeps its own knuffel-validated property set, so invalid
combinations fail at parse time:
- TouchSwipe / TouchpadSwipe: fingers=N (3..=10), direction="up|down|left|right"
- TouchPinch:  fingers=N (3..=10), direction="in|out"
- TouchRotate: fingers=N (3..=10), direction="cw|ccw"
- TouchEdge:   edge="left|right|top|bottom", optional zone=
  (zone vocab rotates per edge axis: top/bottom edges take
   left|center|right; left/right edges take top|center|bottom).

Why:
- Arbitrary finger counts (up to 10) are now supported with zero enum
  churn. Touchscreens and large trackpads that report 6+ contacts are
  no longer capped at 5.
- Syntax matches the rest of niri's KDL config, which already uses
  property-based attributes everywhere (`tag=`, `natural-scroll=`,
  `cooldown-ms=`, `allow-when-locked=`). Touch triggers were the one
  family that hardcoded structural parameters into the node name.
- The old "can't distinguish finger counts at bind lookup" objection
  (from an earlier half-design where the count lived on `Bind` instead
  of inside `Trigger`) is moot: putting `fingers` inside the `Trigger`
  struct variant keeps `Eq`/`Hash`/bind lookup unchanged.

Hard break — no legacy compat:
- Old `TouchSwipe3Up` / `TouchEdgeTop:Left` / `TouchpadSwipe4Left` etc.
  no longer parse. Users get a clear parse error pointing at the new
  property form.
- IPC `GestureBegin.trigger` string wire format also changes: events
  now echo the same property shape that users write in binds, e.g.
  `TouchSwipe fingers=3 direction="up"`. Consumers doing string-match
  on trigger names must adapt.

Implementation:

- `niri-config/src/binds.rs`: Trigger enum refactor with 5 struct
  variants, new `SwipeDirection` / `PinchDirection` / `RotateDirection`
  helper enums, shared `MIN_FINGERS` / `MAX_FINGERS` constants (3..=10),
  private `GestureTriggerProps` + `build_gesture_trigger()` builder
  with per-family validation, `Bind::decode_node` routes gesture-family
  node names to property-based parsing while keyboard / mouse / wheel /
  TouchpadScroll keep the FromStr fast path.
- `niri-config/src/input.rs`: `ScreenEdge::as_kdl_name()` method and
  module-level `zone_kdl_name(edge, zone)` helper as the single source
  of truth for the axis-rotating zone vocabulary. Parser round-trips
  through `zone_kdl_name` instead of hand-rolling the inverse mapping.
- `src/input/touch_gesture.rs`: recognition constructs the new struct
  variants directly from (gesture kind, finger count); `MIN_FINGERS` /
  `MAX_FINGERS` imported from niri-config so there's one range source.
  `trigger_to_ipc_name` takes `Trigger` directly (was `Option<Trigger>`),
  generates the property-form string dynamically, uses `zone_kdl_name`
  and `ScreenEdge::as_kdl_name`, and `debug_assert!`s loudly if it's
  ever called with a non-gesture trigger. Trivial `edge_to_trigger` /
  `edge_zone_to_trigger` wrappers inlined at their two call sites.
- `src/input/mod.rs`: `swipe_trigger()` accepts any N in
  `MIN_FINGERS..=MAX_FINGERS`, not just 3/4/5. The duplicate
  `touchpad_trigger_ipc_name` is deleted; its caller routes through
  `touch_gesture::trigger_to_ipc_name` (which already handled
  `TouchpadSwipe`).
- `src/ui/hotkey_overlay.rs`: display labels generated from fingers +
  direction via helper fns, with `format_touch_edge_label` routing
  through the shared `zone_kdl_name` / `as_kdl_name` helpers.
- `niri-ipc/src/lib.rs`: `GestureBegin.trigger` docstring updated with
  examples of every new family string form.

Note on duplicate properties: knuffel 3.2 stores `SpannedNode::properties`
as `BTreeMap<SpannedName, Value>` and silently takes the last value on
name collision (see knuffel-3.2.0/src/grammar.rs:566). So
`TouchSwipe fingers=3 fingers=5 direction="up"` resolves to `fingers=5`
with no error. This is knuffel-spec behavior, not something niri can
intercept without a separate pre-parse pass over raw KDL source. The
observed last-wins behavior is documented in a regression test.

Tests:
- 15 unit tests in `niri-config/src/binds.rs` exercise
  `build_gesture_trigger` directly: arbitrary fingers=3..=10, per-family
  direction validation, edge zone vocab rejection, fingers out of range.
- 16 integration tests go through `Config::parse_mem`, covering the
  full Bind::decode_node two-phase parse path: modifier stripping
  (`Mod+TouchSwipe ...`, multi-modifier `Mod+Shift+TouchEdge ...`),
  tag on gesture vs keyboard-bind-rejection, gesture property on
  keyboard bind rejection, unknown property rejection, TouchEdge with
  zone and vocab mismatch rejection, TouchpadSwipe with modifier,
  TouchRotate, TouchPinch direction="in" and "out", fingers-out-of-range,
  cross-family direction rejection (swipe rejecting "cw"), and the
  knuffel duplicate-property last-wins behavior.
- Full niri test suite: 198 pass.

Docs:
- `docs/wiki/Gestures.md`: rewritten to document the four node families
  with property grammar and examples, including a rotation section
  that warns about the early-PoC state of rotation recognition.
- `docs/wiki/Configuration:-Input.md`: touchscreen / touchpad tuning
  subblocks updated with the new bind form.
- `docs/wiki/Design:-Touchscreen-Gestures.md` §5.2: rewritten. The
  prior rationale explicitly argued *against* `fingers=N` and for
  hardcoded node names; that position is now reversed, with the new
  section explaining what changed and why.
- `resources/default-config.kdl`: user-facing commented examples
  migrated to the new syntax so first-install users don't copy broken
  snippets.

Pre-existing unrelated issue not touched by this commit: there is a
stale `tests::parse` insta snapshot in `niri-config/src/lib.rs` from
earlier commits that added tag / sensitivity / natural-scroll fields to
`Bind` without refreshing the snapshot. Needs a separate
`cargo insta review` pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Debug-log driven investigation of 5-finger rotation reliability (details
in ~/aaaLOG_Niri analyzer output) surfaced three independent bugs that
together kept drift rotations at 0% and clean rotations at ~80%.

Bug 1 - finger-up spread basis discontinuity
  src/input/touch_gesture.rs on_touch_up
  The rotation basis was rebased on finger-lift but the spread basis
  was not. When a user lifted a finger during unlocked recognition,
  current_spread jumped (geometry change, not finger motion) and
  spread_change = (current - initial).abs() spiked past pinch_threshold
  on the very next frame, latching a spurious PinchIn. Observed as
  finger-lift retries of 5-finger rotations turning into unwanted
  PinchIn at fingers=4.
  Fix: during unlocked recognition with 3+ fingers still down, rebase
  initial_spread to the post-removal geometry so spread_change resets
  to zero across the discontinuity. The locked-pinch rebase already
  handles the other case.

Bug 2 - swipe LOCK has no dominance check
  src/input/touch_gesture.rs FRAME classification
  is_rotate required rotation_arc to dominate swipe_distance by the
  rotation_ratio, but the swipe LOCK branch was a naked threshold
  crossing (swipe_distance >= threshold). Result: any hand drift over
  the swipe threshold (~110 px for 5 fingers) instantly latched as a
  swipe, even when the user was visibly rotating with rot > 40 deg and
  arc > 250 px. The thresholds raced and swipe always won because its
  check was strictly weaker.
  Fix: gate the swipe LOCK branch behind !rotation_candidate, where
  rotation_candidate = (finger_count >= 3 && rotation_arc >=
  rotation_arc_threshold). Once rotation arc is at candidate quality,
  swipe cannot steal via the race - it only latches when rotation is
  not a plausible classification.

Bug 3 - rotation_ratio default inverted vs intent
  niri-config/src/input.rs rotation_ratio
  Default was 0.5, and the is_rotate check does rotation_arc >=
  swipe_distance * (1.0 / rotation_ratio), i.e. arc >= 2 * swipe. For
  a user rotating at 5 fingers with natural hand drift, this gate is
  essentially unreachable - arc is bounded by finger reach, swipe is
  not. Meanwhile pinch_ratio=2.0 is used directly without inversion,
  so the two ratios have opposite semantics for the same field name
  (higher=stricter for pinch, higher=lenient for rotate).
  Fix: bump default from 0.5 to 2.0, giving an effective gate of
  arc >= swipe * 0.5 (rotation arc only needs to be half the swipe
  distance). Doc comment rewritten to reflect the leniency semantics.

Config UX - angle values now in degrees
  niri-config/src/input.rs rotation_threshold, rotation_progress_distance
  rotation-threshold was a raw radian value (default 0.2618) and
  rotation-progress-distance was another (default 1.5708 = pi/2).
  Users reading the KDL had to convert degrees to radians in their
  head. Switched both to degrees in the config surface - accessors
  convert to radians internally, callers see no change. Defaults are
  now 15.0 and 90.0. Docs updated.

Telemetry bars in debug logs
  No new code. The existing TOUCH-DBG FRAME debug_log site at line
  ~819 already emits per-frame swipe/spread/rot/arc/is_rotate/closest
  values which is what the investigation was based on - leaving it as
  is so future debug cycles can reuse the journalctl -> analyze.py
  workflow.

Results on the four-scenario benchmark (5 finger clean/drift/retry):
  baseline: 47% (9/19)  - 5 stolen by swipe, 2 false PinchIn, 1 swipe-steal
  t3 (bug1+bug2): 57%   - drift 0% -> 56%, retry correctly no-motion
  t4 (+ratio fix): 75%  - all remaining failures are user under-rotation
                          (rot < 15 deg threshold) or extreme drift
                          (arc/swipe < 0.5)

Adds Event::RecognitionFrame (debug-only IPC, gated on debug_assertions)
so external tools like niri-gesture-inspector can visualize the
touchscreen gesture classifier state per frame. Also lands an overhaul
of the classifier itself.

Knob rename for clarity:

- All touchscreen + touchpad gesture knobs renamed to a unified
  vocabulary: `*-trigger-distance` (commit gates), `*-progress-distance`
  (IPC scaling), `*-dominance-ratio` (race tuning, "higher = stricter"
  for both pinch and rotation), `*-multi-finger-scale` (per-finger
  multipliers). Same knob names span both touchscreen and touchpad
  blocks; defaults differ because units differ (px vs libinput delta).
- IPC RecognitionFrame + GestureBegin field names match the new
  knob names.
- Doc + default-config.kdl examples updated to match.

Pinch commit-gate bugs fixed:

- The commit gate `(is_pinch && spread_change >= swipe_trigger)` was
  double-gating against the SCALED swipe trigger, so 4/5-finger pinches
  inherited a wildly inflated commit threshold (e.g. 234/378 px at
  swipe-multi-finger-scale 2.6) even though pinch-trigger-distance
  stayed flat. Pinch now commits on `is_pinch` alone — pinch-trigger
  is the single threshold for the pinch path.
- The pinch dominance check had a hardcoded ratio-1.0 fallback ORed
  into the primary gate, capping the effective dominance ratio at
  min(knob, 1.0). Any setting > 1.0 was silently masked. Removed the
  fallback so pinch-dominance-ratio is now a real knob across its full
  range (lower = lenient, higher = stricter).

Default tuning (touchscreen):

- swipe-trigger-distance:    16  → 100
- pinch-trigger-distance:    30  → 100
- pinch-dominance-ratio:     2.0 → 1.0
- swipe-multi-finger-scale:  1.5 → 1.2  (small pinch-priority bias at
                                         4/5-finger so ambiguous motions
                                         resolve as pinch over swipe)
- edge-start-distance:       20  → 30
- rotation-trigger-angle:    15° → 20°

GestureBegin/End emit unconditionally for multi-finger commits:

Multi-finger touchscreen gesture commits now emit GestureBegin/GestureEnd
unconditionally, with an empty `tag` for binds that have no user-set
tag. Previously these events were gated behind `tag.is_some()`, so
debug tools (niri-gesture-inspector) only saw the lock for binds the
user happened to have tagged — making "last lock" stick on the most
recent tagged swipe forever, even when the user was actually
pinching/rotating untagged binds. External consumers filter on tags
they care about, so empty-tag events are a no-op for them. Edge swipes
and touchpad gestures still emit only for tagged binds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add TouchTap { fingers } trigger for binding stationary N-finger taps
(3-10 fingers). Tap detection runs in parallel with swipe/pinch/rotate
recognition using a spatial dead zone — matching the approach used by
Android, iOS, libinput, and Windows.

Tap candidate starts when 3+ fingers land, is killed if any finger
drifts beyond tap-wobble-threshold (default 15px) or when the
recognizer locks a motion gesture, and fires when all fingers lift
within tap-timeout-ms (default 250ms). No latency added to swipe
recognition.

Config: `tap-wobble-threshold` and `tap-timeout-ms` in the
`touchscreen { gestures { } }` block.

Also fixes a pre-existing bug where `touchscreen_gesture_passthrough`
was not cleared in `on_touch_cancel`, which could permanently suppress
gesture recognition after a cancel event on a passthrough window.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Defer gesture recognition and continuous animation feeding from
per-slot on_touch_motion to on_touch_frame. libinput delivers separate
TouchMotion events per finger per hardware scan — previously each one
triggered spread/rotation recalculation, animation feeding, and
queue_redraw_all(). With 3 fingers at 120Hz this caused 360 gesture
updates/sec instead of 120.

Now on_touch_motion only updates positions and accumulates deltas.
on_touch_frame runs recognition + feed once per scan with all
positions final — more efficient and more accurate (spread/rotation
computed on complete geometry instead of partially-updated state).

Also adds TouchTap documentation to the wiki Gestures page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…TouchpadTapHoldDrag)

Add two new touchpad gesture triggers using libinput's hold gesture API:

- TouchpadTapHold: fires on release after stationary hold (3+ fingers).
  Fast taps pass through to clients (e.g. terminal 3-finger paste).
- TouchpadTapHoldDrag: fires when held fingers start moving, reusing
  the existing swipe bind infrastructure for continuous animations.
  Distinguishes from direct swipes via the hold-before-move pause.

Also fixes the pre-existing tests::parse snapshot failure (touch →
touchscreen rename, missing fields on Bind and WindowRule structs).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add TouchTapHoldDrag trigger for touchscreen — fires when fingers hold
stationary (tap candidate alive) then start moving past wobble threshold.
Distinguishes from direct swipes via tap-hold-trigger-delay-ms (default
150ms): fast swipes bypass hold-drag and enter normal recognition.

Supports optional direction= property for per-direction binds after hold
(directional checked first, omnidirectional fallback). Can drive continuous
actions via existing ActiveTouchBind::Swipe infrastructure.

New config knob: tap-hold-trigger-delay-ms in touchscreen gestures block.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- edge-start-distance: 30 → 12 (narrower edge zone feels more natural)
- tap-timeout-ms: 250 → 500 (allows slightly deliberate taps)
- tap-hold-trigger-delay-ms: 150 → 200 (reduces fast-swipe false positives)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add the Gesture IPC Refactor RFC to the wiki — design plan for replacing
the tag system with env-var spawn context, stdin progress pipes, a public
IPC event stream, noop=consume semantics, and per-window binds {} in
window-rules for fingers=1/2 disambiguation. Sourced from PR niri-wm#3771 review
discussion (Atan-D-RP4 originated the core ideas).

Also convert the Status banner on Design:-Touchscreen-Gestures.md from a
bold-prefixed quote to a [!IMPORTANT] admonition, per the docs policy in
Development:-Documenting-niri.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Per Development:-Developing-niri.md, debug! is for normal-operation
messages whose absence shouldn't hurt UX, while trace! is for spammy /
performance-intensive diagnostics — and trace! is compiled out of
release builds.

TOUCH-DBG FRAME fires every motion event during gesture recognition
(multiple times per frame, every gesture). That's textbook trace! —
useful when actively tuning the recognizer, but not something a release
build should pay for.

The other TOUCH-DBG tags (FINGER-LAND, UNLOCK, LOCK, TAP) stay at debug!
since they fire at gesture lifecycle events, which are rare and fit the
"normal operation" definition.

To see FRAME logs in dev builds, use RUST_LOG=niri=trace.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…lots

Multi-finger gesture onset forwards wl_touch.down for the first two
fingers before the 3rd finger flips the gesture gate. The matching up
events are then suppressed by that same gate — leaving clients with
two phantom touch slots, observed as GTK/Qt dialog buttons ignoring
single-finger taps until a two-finger tap happens to reuse those slot
IDs and drain the sequences.

Track forwarded slots in `Niri::touch_forwarded_slots` and at the
transition into gesture tracking emit explicit handle.up for each
previously-forwarded slot plus handle.cancel + handle.frame so the
client can't hold them as phantoms. Clear on all-fingers-up and on
TouchCancel.

The existing handle.cancel at the swipe/pinch/rotate LOCK path still
covers the case where LOCK fires during motion without a new finger
DOWN, but was insufficient for the common 3rd-finger transition path.

Also ships compositor-side TOUCH-DBG FORWARD / BLOCKED / CANCEL-CLIENT
tracing that was essential to diagnose this — the prior assumption
that touch_gesture_locked was sticky turned out wrong, but the logs
immediately revealed the real "first two forwarded, rest blocked"
pattern.

Addresses reviewer report that foot --server scroll/select breaks
after a touch gesture ("self-healed and then re-broke") — same root
cause.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pure formatting changes (whitespace, line wrapping). No logic changes.
Resolves rustfmt CI failure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds a `TouchpadPinch { fingers, direction }` trigger alongside the
existing touchpad gestures. libinput emits pinch events natively for
2/3/4 fingers on touchpads, so the parser accepts fingers=2 here (vs
3+ for touchscreen which reserves 2-finger for client passthrough);
MIN_FINGERS gating is now per-family.

Classifier hooks into on_gesture_pinch_begin/update/end and fires the
bind once per gesture when `|scale - 1.0|` crosses a configurable
threshold. Scale-ratio units (not pixels) since libinput pre-normalizes
touchpad pinch data — new pinch-trigger-scale knob lives under
input.touchpad.gestures alongside swipe-trigger-distance, default 0.15.

Raw pinch events still forward to Wayland clients so app-side
pinch-to-zoom keeps working in parallel with the compositor bind.
Tagged binds emit discrete IPC GestureBegin/End events matching the
TouchpadTapHold pattern.

KDL syntax: `TouchpadPinch fingers=2 direction="in"`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…l.rs)